/*
 * ORACLE PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 */

/*
 *
 *
 *
 *
 *
 * Written by Doug Lea with assistance from members of JCP JSR-166
 * Expert Group and released to the public domain, as explained at
 * http://creativecommons.org/publicdomain/zero/1.0/
 */

package java.util;

/**
 * 用于在处理元素前保存元素的集合。
 * 除了基本的Collection类的操作，queue提供了额外的插入，抽取和检查的操作。
 * 它们的每个方法存在两个形式：如果操作失败，抛出异常。另个一个返回特殊值（null或者false，取决于操作）。
 * 后一种形式的插入操作专门用于容量受限的Queue实现。
 * 在大多数实现，insert操作不会失败。
 * 
 * <p>下面的 抛出异常:add,remove,element，返回特殊值:offer,poll,peek
 * 
 * <table BORDER CELLPADDING=3 CELLSPACING=1>
 * <caption>Queue 方法的总结</caption>
 *  <tr>
 *    <td></td>
 *    <td ALIGN=CENTER><em>抛出异常</em></td>
 *    <td ALIGN=CENTER><em>返回特殊值</em></td>
 *  </tr>
 *  <tr>
 *    <td><b>插入</b></td>
 *    <td>{@link Queue#add add(e)}</td>
 *    <td>{@link Queue#offer offer(e)}</td>
 *  </tr>
 *  <tr>
 *    <td><b>删除</b></td>
 *    <td>{@link Queue#remove remove()}</td>
 *    <td>{@link Queue#poll poll()}</td>
 *  </tr>
 *  <tr>
 *    <td><b>检查</b></td>
 *    <td>{@link Queue#element element()}</td>
 *    <td>{@link Queue#peek peek()}</td>
 *  </tr>
 * </table>
 *
 * <p>队列，通常，但不一定，以FIFO（先进先出）的顺序，排列元素。
 * 例外情况是优先队列（根据提供的比较器，或者元素的自然顺序，排列元素），
 * LIFO的队列（或者栈）（以LIFO，后进先出的顺序，排列元素）。
 * 无论使用的排序是什么，queue的head是下一次调用remove或者poll，被移除的元素。
 * 在一个FIFO的队列，所有的新元素被插入到队列尾部。
 * 其他类型的队列可能使用不同的规则。
 * 每个Queue的实现，必须指定它的排序属性。
 * 
 * <p>如果可以，offer方法插入一个元素，否则返回false。
 * 这与add方法不同，如果失败，抛出一个未检查异常。
 * offer方法是为在失败是正常情况而不是异常情况(例如，在固定容量(或有界)队列中)下使用而设计的。
 * 
 * <p>remove和poll方法删除，并返回队列的头部。
 * 确切地说，从队列中删除哪个元素是队列的排序策略的功能，该功能因实现而异。
 * remove和poll方法仅仅当队列为空时，行为不同：
 * remove方法抛出异常，同时poll方法返回null
 * 
 * <p>element和peek方法返回队列的头部，但是不删除。
 * 
 * <p>Queue接口没有定义阻塞队列的方法，那个在并发编程中很常见。
 * 那些方法等待元素出现，或者有可用的空间，在BlockingQueue中被定义，它扩展了这个接口。
 * 
 * <p>Queue实现通常不允许插入null元素，尽管一些实现，像Linkedlist，不禁止插入null。
 * 即使允许插入null，也不应该插入一个null到Queue，
 * 因为null也被用于poll方法的特殊返回值，表示队列没有元素。
 *
 * <p>队列的实现通常不定义基于元素版本的equals和hashCode方法，
 * 反而继承了Object的基于标识的版本（即内存地址），
 * 因为基于元素的相等性，没有总是为有着相同的元素，但是不同顺序的队列很好地定义。
 *
 *
 *
 * @see java.util.Collection
 * @see LinkedList
 * @see PriorityQueue
 * @see java.util.concurrent.LinkedBlockingQueue
 * @see java.util.concurrent.BlockingQueue
 * @see java.util.concurrent.ArrayBlockingQueue
 * @see java.util.concurrent.LinkedBlockingQueue
 * @see java.util.concurrent.PriorityBlockingQueue
 * @since 1.5
 * @author Doug Lea
 * @param <E> the type of elements held in this collection
 */
public interface Queue<E> extends Collection<E> {
    /**
     * 如果能够立刻插入指定元素到队列，不违反容量的限制，基于成功，返回true。
     * 如果此时没有可用的空间，抛出IllegalStateException
     *
     * @param e the element to add
     * @return {@code true} (as specified by {@link Collection#add})
     * @throws IllegalStateException if the element cannot be added at this
     *         time due to capacity restrictions
     * @throws ClassCastException if the class of the specified element
     *         prevents it from being added to this queue
     * @throws NullPointerException if the specified element is null and
     *         this queue does not permit null elements
     * @throws IllegalArgumentException if some property of this element
     *         prevents it from being added to this queue
     */
    boolean add(E e);

    /**
     * 如果能够立刻插入指定元素到队列，不违反容量的限制，基于成功，返回true。不能插入，返回false。
     * 当使用空间限制的队列，这个方法通常优先于add，add方法失败时，只能抛出异常。
     *
     * @param e the element to add
     * @return {@code true} if the element was added to this queue, else
     *         {@code false}
     * @throws ClassCastException if the class of the specified element
     *         prevents it from being added to this queue
     * @throws NullPointerException if the specified element is null and
     *         this queue does not permit null elements
     * @throws IllegalArgumentException if some property of this element
     *         prevents it from being added to this queue
     */
    boolean offer(E e);

    /**
     * 返回，并删除队列的头部。
     * 这个方法与poll的不同之处为，如果队列为空，抛出异常。
     *
     * @return the head of this queue
     * @throws NoSuchElementException if this queue is empty
     */
    E remove();

    /**
     * 返回，并删除队列的头部。
     * 如果队列为空，返回null。
     *
     * @return the head of this queue, or {@code null} if this queue is empty
     */
    E poll();

    /**
     * 返回，但不删除队列的头部。
     * 这个方法与peek的不同之处为，如果队列为空，抛出异常。
     *
     * @return the head of this queue
     * @throws NoSuchElementException if this queue is empty
     */
    E element();

    /**
     * 返回，但不删除队列的头部。
     * 如果队列为空，返回null。
     *
     * @return the head of this queue, or {@code null} if this queue is empty
     */
    E peek();
}
